…#114)

Fixes GH strands-labs#114. Previously, despite _policy_threads being keyed by
robot_name (implying concurrency), the _require_no_running_policy
helper blocked *any* live Future on every scene mutation AND on every
start_policy call. Two VLA arms could not actually run policies in the
same scene.

The mixin's docstring even said 'per robot' while semantics were serial.

## Semantics changes

start_policy(X):
  * Was: global check — rejected if ANY Future was not done.
  * Now: per-robot check — only rejected if X's own Future is live.
    Policies on different robots can coexist.

remove_robot(X):
  * Was: errored when X had a live policy; required two-step
    stop_policy(X) + remove_robot(X).
  * Now: gracefully stops X's own policy (as before), then runs the
    XML-round-trip ejection. Still errors if a DIFFERENT robot has a
    live policy, because that robot's PolicyRunner holds cached
    actuator/joint IDs that the recompile invalidates.

Scene mutations (add_robot, add_object, add_camera, remove_object,
remove_camera, load_scene, reset, set_gravity, set_timestep, randomize,
apply_force, set_body_properties, set_geom_properties, set_joint_*,
load_state, move_object): still block on ANY live policy. Unchanged.
The error message now NAMES the active-policy robots so the LLM can
stop_policy on each without guessing:

    Cannot 'set_gravity' while a policy is running on 'armA', 'armB'.
    Stop it first: action='stop_policy'.

## New helpers

* _prune_done_futures() — drops completed Futures from
  _policy_threads (GH strands-labs#120 companion fix). Previously the dict grew
  unboundedly and list_policies_running would leak historical names
  as 'running'.
* _active_policy_robots() — returns names with LIVE policies. Prunes
  stale entries as a side-effect so the returned list is authoritative.
* _require_no_running_policy(action_name, robot_name=None) — new
  keyword arg scopes the check to one robot. robot_name=None is the
  existing global-scope behaviour.

## New action

list_policies_running — returns the names of robots with live
policies. Idempotent, always succeeds, prunes stale entries.

Added to tool_spec.json enum and to the tool_spec description so the
LLM discovers it.

## Why this is safe

MuJoCo's mj_step and ctrl[] writes are still serialized via self._lock,
which is the single point that makes concurrent multi-robot policies
safe:

  * Two policies on different robots run in parallel at the inference
    level (observation build, action compute — no shared state).
  * When either calls send_action, it serializes briefly on self._lock
    to write its own ctrl[] slots and advance physics.
  * mj_step advances the WHOLE scene — so two robots sharing a world
    share one physics clock. That's correct: one tick of physical time
    advances all bodies.
  * Each robot writes to a DISJOINT slice of data.ctrl[], indexed by
    actuator IDs specific to that robot's namespaced actuators (set up
    by inject_robot_into_scene via _prefix_robot_names). No ctrl[]
    aliasing.

Documented inline on __init__ and in start_policy's docstring.

## Tests

tests/simulation/mujoco/test_concurrency.py — adds
TestConcurrentPerRobotPolicies class with 6 new tests:

  * test_start_policy_allowed_on_second_robot_while_first_runs
  * test_start_policy_still_rejected_on_SAME_robot
  * test_list_policies_running_reports_active
  * test_completed_futures_are_pruned (GH strands-labs#120 companion)
  * test_scene_mutation_lists_which_robots_are_running
  * test_two_policies_no_segfault_under_stress — actually runs two
    policies to completion and asserts both produced policy_steps > 0

Updated the existing test_remove_robot_blocked_during_policy (which
encoded the old 'error when same-robot policy active' semantics) into
two tests that reflect the new semantics:

  * test_remove_robot_stops_own_policy_and_succeeds
  * test_remove_robot_blocked_by_OTHER_robot_policy

Verified: the new tests fail on pre-fix simulation.py (stashed to
confirm), pass on post-fix code.

## Numbers

* 525 -> 531 passed (+6 new) in tests/simulation/
* hatch run lint: clean (no new errors)
* hatch run format: clean
* CHANGELOG.md updated with both the concurrency change and the new
  list_policies_running action.

Closes strands-labs#114. Companion fix for strands-labs#120 (stale Future pruning).

…strands-labs#116)

Fixes GH strands-labs#116. Previously cleanup() called executor.shutdown(wait=False)
right after setting self._world = None, which opened a race window where
a policy worker still inside mj_step(world._model, world._data) would
segfault on freed arrays. The 'policy_running = False' flag was set but
never awaited.

New cleanup order:
  1. Signal every live policy to stop (policy_running = False).
  2. Await each outstanding Future with a bounded timeout. The on_frame
     hook sees the flag at the top of its next call and raises
     CooperativeStop, which short-circuits run_policy.
  3. Workers that don't stop within the timeout get logged as a warning
     and abandoned — cleanup proceeds rather than hanging the host
     process on exit.
  4. Only AFTER workers have unwound do we null self._world and tear
     down renderers / viewer / executor.

New kwarg: cleanup(policy_stop_timeout=...) for tests and edge cases.
Defaults to 5.0s via a module-level _DEFAULT_POLICY_STOP_TIMEOUT
constant. None (default) uses the constant.

Tests: 4 new in TestCleanupGracefulShutdown:
  * test_cleanup_awaits_running_policy — verifies Future.done() by the
    time cleanup returns
  * test_cleanup_tolerates_wedged_policy — proves cleanup returns in
    bounded time even with an aggressively-short 1ms timeout
  * test_cleanup_is_idempotent_with_no_policies — no-op when there are
    no live Futures
  * test_cleanup_drains_multiple_concurrent_policies — pairs with
    GH strands-labs#114 concurrent-policy support; both robots' futures awaited

All 539 tests pass (was 535; +4 new). Lint clean.

Closes GH strands-labs#119. The mutation guard (_require_no_running_policy) is the
load-bearing safety mechanism that stops the LLM from scheduling a
scene mutation while a policy worker is mid-step. A race between the
guard and the worker's mj_step is a SIGSEGV on stale pointers. We had
a partial stress test in strands-labs#114's commit (two policies run to
completion), but no test that proved:

  * 1000 concurrent main-thread mutation attempts don't starve the
    worker
  * rapid start/stop/start/stop cycles leave _policy_threads clean
  * the first mutation after a policy completes succeeds (no
    lingering guard state)
  * two concurrent policies + 500 main-thread mutations don't deadlock
    on self._lock

New TestMutationGuardStress class covers all four:
  * test_1000_set_gravity_calls_during_policy_never_segfault
  * test_rapid_start_stop_start_stop_policy
  * test_mutation_accepted_immediately_after_policy_completes
  * test_concurrent_policies_stress_no_deadlock (pairs with GH strands-labs#114)

Each test asserts well-formed dict responses (no crashes), specific
status invariants, and the uniform 'policy is running' error shape
when blocked.

All 543 tests pass (was 539; +4 new). Lint clean.

Per user request during autonomous review cycle. The em-dash (—) and
horizontal ellipsis (…) unicode characters sneak in when docstrings
get authored in text editors with smart-quote autocorrect. They look
fine in rendered markdown but are noisy in code and diffs, don't
copy-paste cleanly into terminals, and break grep with non-unicode
patterns.

Bulk replacements:
  * 424 em-dashes ('—' U+2014) -> ' - ' (with normalized spacing) or '-'
    (at line start, mostly bullet points)
  * 8 horizontal-ellipsis ('…' U+2026) -> '...' (three ASCII dots)

Also fixed one arithmetic bug surfaced by the ellipsis replacement:
  * strands_robots/registry/robots.py: description-truncation
    previously subtracted 1 char (for the 1-char ellipsis) and
    appended 3 chars (for '...'), overflowing the table column by
    2 chars. Now subtracts 3.

Files touched:
  * 39 in strands_robots/
  * 30 in tests/
  * 5 in tests_integ/
  * CHANGELOG.md, README.md, AGENTS.md
  * 82 files total

No semantic changes. All 1248 tests pass (was 1236, 5 pre-existing
test_path_validation failures unrelated).

…trands-labs#118)

Partial address of GH strands-labs#118. The review correctly flagged that the
4-way mixin split (PhysicsMixin + RenderingMixin + RecordingMixin +
RandomizationMixin) pretends to describe a decoupling when it really
just describes *where lines live*. Every mixin reaches back into
Simulation for self._world / self._lock / self._mj / _policy_threads /
_renderer_tls, plus the cross-cutting _require_no_running_policy /
_require_world / _prune_done_futures helpers.

Rather than pretend otherwise, this commit makes the coupling
documentary and explicit:

1. simulation.py module-level docstring replaced with a full
   'Architecture notes (honest version)' block that enumerates every
   piece of shared state and every cross-cutting helper the mixins
   rely on. Cross-refs GH strands-labs#118 and commit f5c8518 (which established
   that the alternative -- _SimulationState extraction -- breaks mypy
   narrowing across the helper boundary).

2. Every mixin's class docstring rewritten to name the specific state
   it touches and the specific helpers it calls. Short, precise,
   greppable.

3. TYPE_CHECKING stubs in each mixin updated to reflect the NEW
   per-robot _require_no_running_policy signature (from strands-labs#114) and to
   add _require_world which previously was missing despite being
   used. Now when we edit the real helpers in simulation.py, mypy
   can check the mixin call sites against the intended shape.

4. Class body order normalized: docstring first, THEN TYPE_CHECKING
   block. Previously PhysicsMixin and RandomizationMixin had the stub
   block *before* the class docstring, which hid the real
   documentation.

No runtime behavior change. Lint clean. 543 tests pass.

This leaves the bigger structural question (actually extract
_SimulationState, or merge mixins back into one file) open. That's
tracked on strands-labs#118 -- it's an L/XL refactor and needs its own PR. For
THIS PR, the goal was to stop the split from being *dishonest*.

Cosmetic/quality sweep surfaced a dead return value: _ensure_meshes
returned an error dict on auto-download failure, but the caller at
add_robot (line 494) discarded the return value. Result: the agent
got a cryptic 'mesh not found' from MuJoCo later instead of the clear
'Auto-download failed for X: Y. Install robot_descriptions:...' that
_ensure_meshes constructs.

Changes:
  * _ensure_meshes typed as -> dict[str, Any] | None explicitly
  * Explicit return None on all success paths (previously the function
    fell off the end in places, which implicitly returned None but
    was not self-documenting)
  * Caller in add_robot now checks the return value; propagates any
    error dict and pops the partially-registered robot out of
    self._world.robots before bubbling up

No test change -- the existing happy-path tests still pass, and the
error path requires network-blocked CI to test cleanly (left as
integration territory). Lint and all 543 tests pass.

…abs#117 (on_frame abort)

…trands-labs#125)

Completes the second half of IDEA.md Stage 6 alongside replace_scene_mjcf.
Where replace_scene_mjcf atomically swaps the whole scene for an
agent-written XML string, patch_scene_mjcf applies a list of small
structured ops to the LIVE spec and recompiles once at the end -
cheaper for surgical edits that don't need full-scene XML.

## Tool surface

New action patch_scene_mjcf with one parameter 'ops', a list of dicts.
Supported op kinds (kept narrow on purpose - a wider surface would be
an arbitrary-code hole; exotic MJCF goes through replace_scene_mjcf):

  {'op': 'add_body',      'parent': 'world', 'name': 'foo', 'pos': [...]}
  {'op': 'add_geom',      'body': 'foo',     'type': 'sphere', 'size': [...]}
  {'op': 'add_site',      'body': 'foo',     'name': 'tip', 'pos': [...]}
  {'op': 'set_body_pos',  'name': 'foo',     'pos': [...]}
  {'op': 'set_body_quat', 'name': 'foo',     'quat': [...]}
  {'op': 'delete_body',   'name': 'foo'}

## Atomicity

The whole batch is applied first, then a single spec.recompile(model,
data) is called. If ANY op raises, the spec is restored from an XML
snapshot taken before the batch started and the original error is
re-raised as ValueError - the world is never left in a half-patched
state.

## Implementation notes

Two non-obvious MjSpec 3.8 behaviours addressed:

1. spec.body(name) only resolves bodies that existed at the last
   compile() / recompile(). A body added mid-batch is NOT visible
   through that lookup. Fix: track handles by name in a batch-local
   dict (new_bodies) as we create them, plus a fallback scan over
   spec.bodies for bodies introduced via spec.attach() outside the
   current batch. See _find_body() docstring.

2. MjsBody has no .delete() method - deletion is a spec-level
   operation: spec.delete(body). Caught by the test suite.

## Tests

New tests/simulation/mujoco/test_patch_scene_mjcf.py with 13 cases:
  * happy path: add_body+add_geom, set_body_pos, delete_body,
    add_site, empty ops is no-op.
  * atomic rollback: failed op in middle of batch leaves earlier
    bodies out of the compiled model; missing required field is
    rejected.
  * error paths: no world, non-list input, blocked during policy.
  * tool_spec: action + ops parameter advertised in the schema.
  * state preservation: a post-patch step() still works.

## Totals

- scene_ops.py: 307 -> 481 lines (still well under the 500-line
  success criterion from IDEA.md).
- tests: 415 -> 428 passing (+13, one still skipped).
- lint: ruff + mypy clean across 109 source files.

Closes GH strands-labs#125 stage 6 (agent-authored raw MJCF).

… headless CI

The _can_render() probe used to call mj.Renderer() directly in-process.
On CI environments where libEGL.so.1 is loadable but non-functional
(e.g. no GPU driver), this triggers a C-level abort (SIGABRT) that kills
the entire test process before Python can catch the error.

Fix: run the rendering probe in a subprocess. If the child dies (SIGABRT,
exit code != 0, timeout), _can_render() returns False and rendering tests
are cleanly skipped via @requires_gl.

Also adds @requires_gl to test classes that exercise rendering:
- TestRenderCameraValidation (test_input_validation.py)
- TestRendererTLSCache (test_renderer_hygiene.py)
- TestCamerasRecordingWithoutLerobot (test_recording_backends.py)
- test_render_* (test_error_paths.py)

…ene_mjcf

## The bug

Before this fix:

    >>> sim.create_world()
    >>> sim.replace_scene_mjcf('<mujoco>...</mujoco>')
    >>> sim.export_xml()
    FatalError: No XML model loaded

export_xml() called mj.mj_saveLastXML() which relies on MuJoCo's internal
'last loaded XML' cache. That cache is populated only when the model is
loaded from XML via mj_loadLastXML / MjModel.from_xml_*. After the
MjSpec-based replace_scene_mjcf (which compiles from an MjSpec instead),
the cache is empty and mj_saveLastXML raises a C-level FatalError.

The same bug applies to patch_scene_mjcf - recompiling a spec doesn't
populate MuJoCo's 'last XML' cache either.

## How it was found

Agent-in-the-loop probe at /tmp/e2e_agentic_test_85/notebooks/e2e_agentic_test_85.ipynb
scenario S2_equality: the LLM naturally called export_xml after
replace_scene_mjcf (to verify what it had installed) and the exception
bubbled to the agent as an unhandled tool error. Programmatic tests don't
catch this because they don't mix replace_scene_mjcf with export_xml.

## The fix

Prefer spec.to_xml() when world._backend_state['spec'] is present - the
MjSpec is always canonical. Fall back to mj_saveLastXML only when no
spec is tracked (legacy load_scene paths that bypass SpecBuilder).

Also: file-write path now uses plain file I/O (open + write) instead of
mj_saveLastXML so the --output-path flow works uniformly.

## Tests

New tests/simulation/mujoco/test_export_xml_after_replace.py with 4 cases:
  * export after replace_scene_mjcf returns the new scene's XML
  * export after patch_scene_mjcf returns the patched scene's XML
  * export(--output=path) writes a file containing the patched scene
  * export before create_world still errors cleanly (unchanged)

## Totals

- hatch run test tests/simulation/mujoco/: 432 passed, 1 skipped (was 428)
- hatch run lint: ruff + mypy clean across 110 source files
- /tmp/e2e_agentic_test_85 rerun: 5/5 scenarios will now pass cleanly